General information: DiGIR Concepts and Requests

Distributed Generic Information Retrieval (DiGIR) describes two different but related concepts:

A federated database system with a Client / Server architecture (called Provider / Portal in DiGIR nomenclature).
A communication protocol used to exchange information between the Provider and Portal. The DiGIR protocol only supports a single exchange of data between the Provider and Portal: the Portal sends a request to the Provider and the Provider responds to the request.
The DiGIR protocol defines its own request standard, and uses the Darwin Core (DwC) standard to define any fields used in the request. XML over HTTP is used for the exchange of requests and result sets between the Portal and Provider.
Note: The EMu DiGIR Provider software can be configured to interface with any EMu database.

Requests

The DiGIR protocol provides for three types of request:

Metadata	A metadata request returns content that describes the data provider service. For example, see metadataResponseExample.xml
Inventory	An inventory request returns an aggregate of the unique values of one field with an optional count of the number of occurrences of the values. For example, see inventoryResponseExample.xml
Search	A search request returns a record for each database record that matches the search request criteria. The returned record comprises the values of the requested Darwin Core fields. For example, see searchResponseDiGIR1.5.xml

All DiGIR responses have the same basic form: a wrapper comprising general information wrapped around the response content.

More information can be found at:

The DiGIR homepage
The Darwin Core homepage

DiGIR concepts

General concepts

Concepts	Details
DiGIR	Distributed Generic Information Retrieval
Handler (TexQL)	PHP code specified in a Client Specific Resource Object (see below) and stored in the mapping object that generates TexQL when a post-processed Darwin Core field is queried in a DiGIR request. This mechanism is required because if all or part of a field is generated from data that is not contained in the database, it is necessary to handle incoming requests that include that data so that the correct TexQL is generated. See TexQL and Value handlers for more detail.
Handler (Value)	PHP code specified in a Client Specific Resource Object (see below) and stored in the mapping object that builds or modifies Darwin Core field data before returning it in the DiGIR response. See TexQL and Value handlers for more detail.
Client Specific Resource Object	Client specific PHP object that describes an individual resource and can provide methods to customise the default DiGIR Provider behaviour and output.
DiGIR Resources Object	Client specific PHP object that describes and can generate the resources specified for that Provider and some parts of the client's metadata (those parts that apply to all of that Provider's resources).
Mandatory field	Darwin Core field that must contain data in order for that DiGIR record to be included in the DiGIR response.
Mapping	Relationship between Darwin Core field names and EMu column names. See Mappings.
Post-processing	A term used as short hand for the process in which the data for a Darwin Core field is created or modified on the fly by the DiGIR Provider. Part of the Darwin Core field data may be retrieved from the database or the data may be built completely from scratch from data specified in the Client Specific Resource Object. See also Handler (TexQL) and Handler (Value).
Provider	Abstract term for an entity that provides a DiGIR service. Essentially synonymous with each instance of the EMu server. Also the term used to describe the set of scripts that handles DiGIR requests.
Record (DiGIR/DwC)	Portion of DiGIR XML response wrapped in `record` tags. Constructed from requested Darwin Core field values -see structure in the Request / Response concepts table.
Resource	Specifies a logical set of records amongst the entire set provided by the Provider. This could be all or a subset of the records. Multiple resources are allowed for each Provider.
Resource Code	The code that uniquely identifies each resource of the Provider. For example, `NMNH-IZ` identifies the National Museum of Natural History Invertebrate Zoology resource.
Resource Restrictions	TexQL statement(s) specified in the Client Specific Resource Object that limit DiGIR responses to records belonging to a certain resource.
Request	The XML document sent to the Provider's accessPoint to elicit a response. Formatted as per the DiGIR protocol.
Response	The XML document generated when a request is received at the accessPoint. Formatted as per the DiGIR protocol.

Request / Response concepts

Concepts	Request / Response	Definition / Details
accessPoint	Metadata response	The URL where DiGIR queries are accepted. For EMu DiGIR implementations this will always be `http://server/webdirname/webservices/digir.php`
count	Inventory request	Optional part of the DiGIR XML inventory request. If specified and has the value `true`, returns the total number of each unique value of the requested Darwin Core inventory field.
dateLastUpdated	Metadata response	The `DateTime` the Provider was last updated.
diagnostics	Metadata / Inventory / Search response	Portion of DiGIR XML response that contains messages generated by the Provider. Messages can be general information, warnings, errors, etc.
filter	Inventory / Search request	Specifies which records to return in the DiGIR XML response. Analogous to an SQL or TexQL `where` statement. Optional for inventory requests, mandatory for search requests.
inventory	Request / response type	As a request it specifies a single Darwin Core field and an optional count and filter. As a response it returns all unique values of the Darwin Core field.
limit	Search request	Attribute of the `records` tag. Used with start to provide a method of iterating through all of the records of a resource if they total more than maxSearchResponseRecords. Specifies the maximum number of records to return in a results set.
maxSearch ResponseRecords	Metadata response	The maximum number of records that will be returned in any single DiGIR search request. The default value for the EMu DiGIR Provider is 1000.
maxInventory ResponseRecords	Metadata response	The maximum number of records that will be returned in any single DiGIR inventory request. See maxInventoryResponseRecords.
metadata	Request / response type	There is no specification beyond the basic request layout required for a metadata request. As a response it returns the resource metadata which contains information about that resource.
numberOfRecords	Metadata response	The total number of valid DiGIR records that the resource provides. See Mandatory Darwin Core fields.
records	Search request	Specifies record start and record limit. Contains the record structure.
search	Request / response type	As a request it specifies a filter and a record structure. As a response it returns all of the records for that resource that match the filter in the format specified by the record structure.
start	Search request	Attribute of the `records` tag. Used with limit to provide a method of iterating through all of the records of a resource if they total more than maxSearchResponseRecords. Specifies which record in the set of records that match the DiGIR query with which to begin the results set. Starts from 0. Analogous to TexQL row number selection.
structure	Search request	Specifies how to build a DiGIR XML response record. Analogous to an SQL or TexQL `select` statement.

➤